4.9 Connecting to a remote host using multiple hops

Sometimes, the methods described before are not sufficient. Sometimes, it is not possible to connect to a remote host using a simple command. For example, if you are in a secured network, you might have to log in to a `bastion host' first before you can connect to the outside world. Of course, the target host may also require a bastion host.

In order to specify such multiple hops, it is possible to define a proxy host to pass through, via the variable tramp-default-proxies-alist. This variable keeps a list of triples (host user proxy).

The first matching item specifies the proxy host to be passed for a file name located on a remote target matching user@host. host and user are regular expressions or nil, which is interpreted as a regular expression which always matches.

proxy must be a Tramp filename which localname part is ignored. Method and user name on proxy are optional, which is interpreted with the default values. The method must be an inline or gateway method (see Inline methods, see Gateway methods). If proxy is nil, no additional hop is required reaching user@host.

If you, for example, must pass the host ‘bastion.your.domain’ as user ‘bird’ for any remote host which is not located in your local domain, you can set

     (add-to-list 'tramp-default-proxies-alist
                  '("\\." nil "/ssh:bird
@bastion.your.domain:"))
     (add-to-list 'tramp-default-proxies-alist
                  '("\\.your\\.domain\\'" nil nil))

Please note the order of the code. add-to-list adds elements at the beginning of a list. Therefore, most relevant rules must be added last.

Proxy hosts can be cascaded. If there is another host called ‘jump.your.domain’, which is the only one in your local domain who is allowed connecting ‘bastion.your.domain’, you can add another rule:

     (add-to-list 'tramp-default-proxies-alist
                  '("\\`bastion\\.your\\.domain\\'"
                    "\\`bird\\'"
                    "/ssh:jump.your.domain:"))

proxy can contain the patterns %h or %u. These patterns are replaced by the strings matching host or user, respectively.

If you, for example, wants to work as ‘root’ on hosts in the domain ‘your.domain’, but login as ‘root’ is disabled for non-local access, you might add the following rule:

     (add-to-list 'tramp-default-proxies-alist
                  '("\\.your\\.domain\\'" "\\`root\\'" "/ssh
:%h:"))

Opening /sudo :randomhost.your.domain: would connect first ‘randomhost.your.domain’ via ssh under your account name, and perform sudo -u root on that host afterwards. It is important to know that the given method is applied on the host which has been reached so far. sudo -u root, applied on your local host, wouldn't be useful here.

host, user and proxy can also be Lisp forms. These forms are evaluated, and must return a string, or nil. The previous example could be generalized then: For all hosts except my local one connect via ssh first, and apply sudo -u root afterwards:

     (add-to-list 'tramp-default-proxies-alist
                  '(nil "\\`root\\'" "/ssh:%h:"))
     (add-to-list 'tramp-default-proxies-alist
                  '((regexp-quote (system-name)) nil nil))

This is the recommended configuration to work as ‘root’ on remote Ubuntu hosts.

Finally, tramp-default-proxies-alist can be used to pass firewalls or proxy servers. Imagine your local network has a host ‘proxy.your.domain’ which is used on port 3128 as HTTP proxy to the outer world. Your friendly administrator has granted you access under your user name to ‘host.other.domain’ on that proxy server.¹ You would need to add the following rule:

     (add-to-list 'tramp-default-proxies-alist
                  '("\\`host\\.other\\.domain\\'" nil
                    "/tunnel:proxy.your.domain#3128:"))

Gateway methods can be declared as first hop only in a multiple hop chain.